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ABOUT THIS CHAPTER 


This chapter describes the Control Manager, the part of the Toolbox that deals 
with controls, such as buttons, check boxes, and scroll bars. Using the Control 
Manager, your application can create, manipulate, and dispose of controls. 


You should already be familiar with: 


* resources, as discussed in the Resource Manager chapter 

¢ the basic concepts and structures behind QuickDraw, particularly points, 
rectangles, regions, and grafPorts 

« the Toolbox Event Manager 

¢ the Window Manager 


This chapter also describes the enhancements to the Control Manager provided for 
the Macintosh Plus, Macintosh SE, and Macintosh II. A new set of Control Manager 
routines now supports the use of color controls. All handling of color controls 
is transparent to applications that aren't using the new features. 


The structure and size of a control record are unchanged. A new data structure, 
the auxiliary control record, has been introduced to carry additional color 
information for a control, and a new system resource, ‘cctb', stores control 
color table information. Three new routines have been added to support the use 
of color. 
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ABOUT THE CONTROL MANAGER 


The Control Manager is the part of the Toolbox that deals with controls. A 

control is an object on the Macintosh screen with which the user, using the 
mouse, can cause instant action with visible results or change settings to 

modify a future action. Using the Control Manager, your application can: 


create and dispose of controls 

display or hide controls 

monitor the user's operation of a control with the mouse and 
respond accordingly 

read or change the setting or other properties of a control 
change the size, location, or appearance of a control 


Your application performs these actions by calling the appropriate Control 
Manager routines. The Control Manager carries out the actual operations, but 
it's up to you to decide when, where, and how. 


Controls may be of various types (see Figure 1), each with its own 
characteristic appearance on the screen and responses to the mouse. Each 
individual control has its own specific properties— such as its location, size, 
and setting—but controls of the same type behave in the same general way. 


Certain standard types of controls are predefined for you. Your application can 
easily create and use controls of these standard types, and can also define its 
own "custom" control types. Among the standard control types are the following: 


e 


Buttons cause an immediate or continuous action when clicked or pressed 
with the mouse. They appear on the screen as rounded-corner rectangles 
with a title centered inside. 


Check boxes retain and display a setting, either checked (on) or 
unchecked (off); clicking with the mouse reverses the setting. On the 
screen, a check box appears as a small square with a title alongside it; 
the box is either filled in with an "X" (checked) or empty (unchecked). 
Check boxes are frequently used to control or modify some future action, 
instead of causing an immediate action of their own. 


Radio buttons also retain and display an on-or-off setting. They're 
Organized into groups, with the property that only one button in the 
group can be on at a time: Clicking one button in a group both turns it 
on and turns off the button that was on, like the buttons on a car radio. 
Radio buttons are used to offer a choice among several alternatives. On 
the screen, they look like round check boxes; the radio button that's on 
is filled in with a small black circle instead of an "X". 
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Figure 1-Controls 


Figure 1-Controls 


Note: The Control Manager doesn't know how radio buttons are grouped, 
and doesn't automatically turn one off when the user clicks another 
one on: It's up to your program to handle this 


Another important category of controls is dials. These display the value, 
magnitude, or position of something, typically in some pseudo-analog form such 
as the position of a sliding switch, the reading on a thermometer scale, or the 
angle of a needle on a gauge; the setting may be displayed digitally as well. 
The control's moving part that displays the current setting is called the 
indicator. The user may be able to change a dial's setting by dragging its 
indicator with the mouse, or the dial may simply display a value not under the 
user's direct control (such as the amount of free space remaining on a disk). 


One type of dial is predefined for you: The standard Macintosh scroll bars. 
Figure 2 shows the five parts of a scroll bar and the terms used by the Control 
Manager (and this chapter) to refer to them. Notice that the part of the scroll 
bar that Macintosh users know as the "scroll box" is called the "thumb" here. 
Also, for simplicity, the terms "up" and "down" are used even when referring to 
horizontal scroll bars (in which case "up" really means "Left" and "down" means 
"right"). 
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Figure 2—Parts of a Scroll Bar 


Figure 2—Parts of a Scroll Bar 


The up and down arrows scroll the window's contents a line at a time. The two 
paging regions scroll a "page" (windowful) at a time. The thumb can be dragged 
to any position in the scroll bar, to scroll to a corresponding position within 
the document. Although they may seem to behave like individual controls, these 
are all parts of a single control, the scroll bar type of dial. You can define 
other dials of any shape or complexity for yourself if your application needs 
them. 


A control may be active or inactive. Active controls respond to the user's mouse 
actions; inactive controls don't. When an active control is clicked or pressed, 
it's usually highlighted (see Figure 3). Standard button controls are inverted, 
but some control types may use other forms of highlighting, such as making the 
outline heavier. It's also possible for just a part of a control to be 
highlighted: For example, when the user presses the mouse button inside a 
scroll arrow or the thumb in a scroll bar, the arrow or thumb (not the whole 
scroll bar) becomes highlighted until the button is released. 
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Figure 3-Highlighted Active Controls 
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Figure 3—Highlighted Active Controls 


A control is made inactive when it has no meaning or effect in the current 
context, such as an "Open" button when no document has been selected to open, or 
a scroll bar when there's currently nothing to scroll to. An inactive control 
remains visible, but is highlighted in some special way, depending on its 
control type (see Figure 4). For example, the title of an inactive button, check 
box, or radio button is dimmed (drawn in gray rather than black). 
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Figure 4-Inactire Controls 


Figure 4—Inactive Controls 


@ SpInside Macintosh ¢ Version 1.0 * November 1989 * Apple Computer 
THE CONTROL MANAGER e 7 of 45 


CONTROLS AND WINDOWS 


Every control "belongs" to a particular window: When displayed, the control 
appears within that window's content region; when manipulated with the mouse, it 
acts on that window. All coordinates pertaining to the control (such as those 
describing its location) are given in its window's local coordinate system. 


Warning: In order for the Control Manager to draw a control properly, the 
control's window must have the top left corner of its grafPort's 
portRect at coordinates (0,0). If you change a window's local 
coordinate system for any reason (with the QuickDraw procedure 
SetOrigin), be sure to change it back—so that the top left corner 
is again at (0,0)—before drawing any of its controls. Since almost 
all of the Control Manager routines can (at least potentially) 
redraw a control, the safest policy is simply to change the 
coordinate system back before calling any Control Manager routine. 


Normally you'll include buttons and check boxes in dialog or alert windows only. 
You create such windows with the Dialog Manager, and the Dialog Manager takes 
care of drawing the controls and letting you know whether the user clicked one 
of them. See the Dialog Manager chapter for details. 
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CONTROLS AND RESOURCES 


The relationship between controls and resources is analogous to the relationship 
between windows and resources: Just as there are window definition functions 
and window templates, there are control definition functions and control 
templates. 


Each type of control has a control definition function that determines how 
controls of that type look and behave. The Control Manager calls the control 
definition function whenever it needs to perform a type-dependent action, such 
as drawing the control on the screen. Control definition functions are stored as 
resources and accessed through the Resource Manager. The system resource file 
includes definition functions for the standard control types (buttons, check 
boxes, radio buttons, and scroll bars). If you want to define your own, 
nonstandard control types, you'll have to write control definition functions for 
them, as described later in the section "Defining Your Own Controls". 


When you create a control, you specify its type with a control definition ID, 
which tells the Control Manager the resource ID of the definition function for 
that control type. The Control Manager provides the following predefined 
constants for the definition IDs of the standard control types: 


CONST pushButProc = 0; {simple button} 
checkBoxProc = 1; {check box} 
radioButProc = 2; {radio button} 
scrollBarProc = 16; {scroll bar} 


Note: The control definition function for scroll bars figures out whether 
a scroll bar is vertical or horizontal from a rectangle you specify 
when you create the control. 


The title of a button, check box, or radio button normally appears in the system 
font, but you can add the following constant to the definition ID to specify 
that you instead want to use the font currently associated with the window's 
grafPort: 


CONST useWFont = 8; {use window's font} 


To create a control, the Control Manager needs to know not only the control 
definition ID but also other information specific to this control, such as its 
title (if any), the window it belongs to, and its location within the window. 
You can supply all the needed information in individual parameters to a Control 
Manager routine, or you can store it in a control template in a resource file 
and just pass the template's resource ID. Using templates is highly recommended, 
since it simplifies the process of creating controls and isolates the control 
descriptions from your application's code. 
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PART CODES 


Some controls, such as buttons, are simple and straightforward. Others can be 
complex objects with many parts: For example, a scroll bar has two scroll 
arrows, two paging regions, and a thumb (see Figure 2 above). To allow different 
parts of a control to respond to the mouse in different ways, many of the 
Control Manager routines accept a part code as a parameter or return one as a 
result. 


A part code is an integer between 1 and 253 that stands for a particular part of 
a control. Each type of control has its own set of part codes, assigned by the 
control definition function for that type. A simple control such as a button or 
check box might have just one "part" that encompasses the entire control; a more 
complex control such as a Scroll bar can have as many parts as are needed to 
define how the control operates. 


Note: The values 254 and 255 aren't used for part codes—254 is reserved 
for future use, and 255 means the entire control is inactive. 


The part codes for the standard control types are as follows: 


CONST inButton = 10; {simple button} 
inCheckBox = 11; {check box or radio button} 
inUpButton = 20; {up arrow of a scroll bar} 
inDownButton = 21; {down arrow of a scroll bar} 
inPageUp = 22; {"page up" region of a scroll bar} 
inPageDown = 23; {"page down" region of a scroll bar} 
inThumb = 129; {thumb of a scroll bar} 


Notice that inCheckBox applies to both check boxes and radio buttons. 


Note: For special information about assigning part codes to your own 
control types, see "Defining Your Own Controls". 


CONTROL RECORDS 


Every control is represented internally by a control record containing all 
pertinent information about that control. The control record contains the 
following: 


e A pointer to the window the control belongs to. 

e A handle to the next control in the window's control list. 

e A handle to the control definition function. 

e The control's title, if any. 

« A rectangle that completely encloses the control, which determines 
the control's size and location within its window. The entire control, 
including the title of a check box or radio button, is drawn inside 
this rectangle. 
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¢ An indication of whether the control is currently active and how it's 
to be highlighted. 

e The current setting of the control (if this type of control retains a 
setting) and the minimum and maximum values the setting can assume. For 
check boxes and radio buttons, a setting of 0 means the control is off 
and 1 means it's on. 


The control record also contains an indication of whether the control is 
currently visible or invisible. These terms refer only to whether the control is 
drawn in its window, not to whether you can see it on the screen. A control may 
be "visible" and still not appear on the screen, because it's obscured by 
overlapping windows or other objects. 


There's a field in the control record for a pointer to the control's default 
action procedure. An action procedure defines some action to be performed 
repeatedly for as long as the user holds down the mouse button inside the 
control. The default action procedure may be used by the Control Manager 
function TrackControl if you call it without passing a pointer to an action 
procedure; this is discussed in detail in the description of TrackControl in the 
"Control Manager Routines" section. 


Finally, the control record includes a 32-bit reference value field, which is 
reserved for use by your application. You specify an initial reference value 
when you create a control, and can then read or change the reference value 
whenever you wish. 


The data type for a control record is called ControlRecord. A control record is 
referred to by a handle: 


TYPE ControlPtr 
ControlHandle 


= “ControlRecord; 

= “ControlPtr; 

The Control Manager functions for creating a control return a handle to a newly 
allocated control record; thereafter, your program should normally refer to the 
control by this handle. Most of the Control Manager routines expect a control 
handle as their first parameter. 


You can store into and access most of a control record's fields with Control 
Manager routines, so normally you don't have to know the exact field names. 
However, if you want more information about the exact structure of a control 
record—if you're defining your own control types, for instance—-it's given below. 


The ControlRecord Data Type 
The ControlRecord data type is defined as follows: 


TYPE ControlRecord = 
PACKED RECORD 


nextControl: ControlHandle; {next control} 
contrlOwner: WindowPtr; {control's window} 
contrlRect: Rect; {enclosing rectangle} 
contrlVis: Byte; {255 if visible} 
contrlHilite: Byte; {highlight state} 
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contrlValue: INTEGER; {control's current setting} 


contrlMin: INTEGER; {control's minimum setting} 
contrlMax: INTEGER; {control's maximum setting} 
contrlDefProc: Handle; {control definition function} 
contrlData: Handle; {data used by contrlDefProc} 
contrlAction: ProcPtr; {default action procedure} 
contrlRfCon: LONGINT; {control's reference value} 
contrlTitle: Str255 {control's title} 

END; 


NextControl is a handle to the next control associated with this control's 
window. All the controls belonging to a given window are kept in a linked list, 
beginning in the controlList field of the window record and chained together 
through the nextControl fields of the individual control records. The end of the 
list is marked by a NIL value; as new controls are created, they're added to the 
beginning of the list. 


ContrlOwner is a pointer to the window that this control belongs to. 


ContrlRect is the rectangle that completely encloses the control, in the local 
coordinates of the control's window. 


When contrlVis is 0, the control is currently invisible; when it's 255, the 
control is visible. 


ContrlHilite specifies whether and how the control is to be highlighted, 
indicating whether it's active or inactive. The HiliteControl procedure lets you 
set this field; see the description of HiliteControl for more information about 
the meaning of the field's value. 


ContrlValue is the control's current setting. For check boxes and radio buttons, 
@ means the control is off and 1 means it's on. For dials, the fields contrlMin 

and contrlMax define the range of possible settings; contrlValue may take on any 
value within that range. Other (custom) control types can use these three fields 
as they see fit. 


ContrlDefProc is a handle to the control definition function for this type of 
control. When you create a control, you identify its type with a control 
definition ID, which is converted into a handle to the control definition 
function and stored in the contrlDefProc field. Thereafter, the Control Manager 
uses this handle to access the definition function; you should never need to 
refer to this field directly. 


Note: When not running in 32-bit mode, the high-order byte of the 
contrlDefProc field contains some additional information that 
the Control Manager gets from the control definition ID; for 
details, see the section "Defining Your Own Controls". 


ContrlData is reserved for use by the control definition function, typically to 
hold additional information specific to a particular control type. For example, 
the standard definition function for scroll bars uses this field for a handle to 
the region containing the scroll bar's thumb. If no more than four bytes of 
additional information are needed, the definition function can store the 
information directly in the contrlData field rather than use a handle. 


@ SpInside Macintosh * Version 1.0 * November 1989 * Apple Computer 
THE CONTROL MANAGER ¢ 12 of 45 


ContrlAction is a pointer to the control's default action procedure, if any. The 
Control Manager function TrackControl may call this procedure to respond to the 
user's dragging the mouse inside the control. 


ContrlRfCon is the control's reference value field, which the application may 
store into and access for any purpose. 


ContrlTitle is the control's title, if any. 


@ SpInside Macintosh « Version 1.0 * November 1989 * Apple Computer 
THE CONTROL MANAGER ¢ 13 of 45 


AUXILIARY CONTROL RECORDS 


The information needed for drawing controls in color is kept in a linked list of 
auxiliary control records, beginning in the global variable AuxCtlHead. 

(Notice that there is just one global list for all controls in all windows, not 

a separate one for each window.) Each window record has a handle to the list of 

controls. Figure 5 shows the auxiliary control list structure. 


first AuxRec second AuxRec default Red 
AuxCtHead —fee aclext ————e aclfext ———f acMext ———e NIL 

aclrwiner aclwiier aclrwner 

act? Table act? Table aclTahble 

acFlavs acFlars acFlass 

acreserved acFeserved acFeserved 

acReflon acRefCon acReflon 
first seco default 
contiol*s contol’s ColorTable 
olorTable ColorTable 


Figure 5—-Auriliary Control List 
Figure 5—Auxiliary Control List 


Each auxiliary control record is a relocatable object residing in the 
application heap. The most important information it holds is a handle to the 
control's individual color table (see the "Control Color Tables" section). The 
rest of the record consists of a link to the next record in the list, a field 
that identifies the control's owner, a 4-byte field reserved for future 
expansion, and a 4-byte reference constant for use by the application: 


TYPE 
AuxCtlHandle = *AuxCtlPtr; 
AuxCtlPtr = “AuxCtlRec; 
AuxCtlRec = RECORD 
acNext: AuxCtlHandle; {handle to next record in list} 
acOwner: ControlHandle; {handle to owning control} 
acCTable: CCTabHandle; {handle to control's color } 
{ table} 
acFlags: INTEGER; {miscellaneous flags; reserved} 
acReserved: LONGINT; {reserved for future expansion} 
acRefCon: LONGINT {reserved for application use} 
END; 
Field descriptions 
acNext The acNext field contains a handle to the next record in 


the auxiliary control list. 
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acQOwner The acOwner field contains the handle of the control to 
which this auxiliary record belongs. Used as an ID field. 


acCTable The acCTable contains the handle to the control's color 
table (see "Control Color Tables" below). 


acFlags The acFlags field contains miscellaneous flags for use by 
the Control Manager; this field is reserved. 


acReserved The acReserved field is reserved for future expansion; 
this must be set to 0 for future compatibility. 


acRefCon The acRefCon field is a reference constant for use by 
the application. 


Not every control needs an auxiliary control record. When an application is 
started, a resource containing a default color table is loaded from the system 
resource file; this resource defines a standard set of control colors. Since 
there is no InitControls routine, this happens when an application calls 
InitWindows. 


Separate auxiliary control records are needed only for controls whose color 
usage differs from the default. Each such nonstandard control must have its own 
auxiliary record, even if it uses the same colors as another control. This 
allows two or more auxiliary records to share the same control color table. If 
the control color table is a resource, it won't be deleted by DisposeControl. 
When using an auxiliary record that is not stored as a resource, the application 
should not deallocate the color table if another control is still using it. 


A control created from scratch will initially have no auxiliary control record. 
If it is to use nonstandard colors, it must be given an auxiliary record and a 
color table with SetCtlColor (see the "Control Manager Routines" section). Such 
a control should normally be made invisible at creation and then displayed with 
ShowControl after the colors are set. For controls created from a 'CNTL' 
resource, the color table can be specified as a resource as well. See the 
section titled "The Control Color Table Resource". 


A/UX systems: When using 32-bit mode. every control has its own auxiliary 
record. If there is no specific set of control colors for 
this control, the acCTable will point to the default color table. 
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CONTROL COLOR TABLES 


The contents and meaning of a control's color table are determined by its 
control definition function (see "The Control Color Table Resource" section). 
The CTabHandle parameter used in the Color Control Manager routines provides a 
handle to the control color table. The components of a control color table are 
defined as follows: 


TYPE 

CCTabHandle = *CCTabPtr; 

CCTabPtr = *“CtlCTab; 

CtlCTab = RECORD 
ccSeed: LONGINT; {not used for controls} 
ccRider: INTEGER; {not used for controls} 
ctSize: INTEGER; {number of entries in table —1} 
ctTable: cSpecArray {array of ColorSpec records} 

END; 


Field descriptions 


ccSeed 
ccRider 


ctSize 


ctTable 


The ccSeed field is unused in control color tables. 
The ccRider field is unused in control color tables. 


The ctSize field defines the number of elements in the table, 
minus one. For controls drawn with the standard definition 
procedure, this field is always 3. 


The ctTable field holds an array of colorSpec records. Each 
colorSpec is made up of a partIdentifier field and a partRGB 
field. The partIdentifier field holds an integer which 
associates an RGBColor to a particular part of the control. 
The definition procedures attempt to find the appropriate part 
identifier when preparing to draw a part. If that part 
identifier is not found, the first color in the table is 

used to draw the part. The part identifiers can appear in any 
order in the table. The partRGB field specifies a standard RGB 
color record, indicating what absolute color will be used to 
draw the control part found in the partIdentifier field. 


A standard control color table is shown in Figure 6. 
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Figure 6-—Control Color Table 
Figure 6—Control Color Table 


The 'cctb' resource is an exact image of this control table data structure, and 
is stored in the same format as 'clut' color table resources. 


Standard buttons, check boxes, and radio buttons use a four-element color table 
with part identifiers as shown below: 


cFrameColor (0) Frame color 

cBodyColor (1) Fill color for body of control 
cTextColor (2) Text color 

cThumbColor (3) Unused 


When highlighted, plain buttons exchange their body and text colors (colors 1 
and 2); check boxes and radio buttons change their appearance without changing 
colors. All three types indicate deactivation by dimming their text with no 
change in colors. 


Standard scroll bars use a four-element color table with part identifiers as 
shown below: 


cFrameColor (Q) Frame color, foreground color for shaft and arrows 
cBodyColor (1 Background color for shaft and arrows 

cTextColor (2) Unused 

cThumbColor (3) Fill color for thumb 


When highlighted, the arrows are filled with the foreground color (color Q@) 
within the arrow outline. A deactivated scroll bar shows no indicator, and 
displays its shaft in solid background color (color 1), with no pattern. 


The ‘cctb' resource = 0 is read into the application heap when the application 
starts, and serves as the default control color table. The last record in the 
auxiliary control list points to the default ‘cctb' resource. When drawing a 
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control, the standard control definition function searches the list for an 
auxiliary control record whose acOwner points to the control being drawn. If it 
finds such a record, it uses the color table designated by that record; if it 
doesn't find one before reaching the default record at the end of the list, it 
uses the default color table instead. All types of controls share the same 
default record. The default auxiliary control record is recognized by NIL values 
in both its acNext and acOwner fields; the application must not change these 
fields. 


A nonstandard control definition function can use color tables of any desired 
size and define their contents in any way it wishes, except that part indices 1 
to 127 are reserved for system definition. Any such nonstandard function should 
take care to bypass the defaulting mechanism just described, by allocating an 
explicit auxiliary record for every control it creates. 
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THE CONTROL COLOR TABLE RESOURCE 


The system default control colors are stored in the System file and ROMResources 
as 'cctb' resource = 0. By including a '‘cctb' resource = 0 in your application, 
it is possible to change the default colors that will be used for all controls, 
unless a specific 'cctb' exists for a control defined within the application. 


When you use GetNewControl for the control resource 'CNTL', GetNewControl will 
attempt to load a ‘cctb' resource with the same ID as the 'CNTL' resource ID, if 
one is present. It then executes the SetCtlColor call. 


The following part identifiers for control elements should be present in the 
ColorSpec.value field: 


cFrameColor (0) Frame color 
cBodyColor (1) Fill color for body of control 
cTextColor (2) Text color 
cThumbColor (3) Thumb color 


These identifiers may be present in any order; for instance, the text or 
indicator color values may be stored before the fill and frame colors in the 
ColorSpec record structure. If a part identifier is not found, then the first 
color in the color table will be used. 
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USING THE CONTROL MANAGER 


To use the Control Manager, you must have previously called InitGraf to 
initialize QuickDraw, InitFonts to initialize the Font Manager, and InitWindows 
to initialize the Window Manager. 


Note: For controls in dialogs or alerts, the Dialog Manager makes some 
of the basic Control Manager calls for you; see the Dialog Manager 
chapter for more information. 


Where appropriate in your program, use NewControl or GetNewControl to create any 
controls you need. NewControl takes descriptive information about the new 
control from its parameters; GetNewControl gets the information from a control 
template in a resource file. When you no longer need a control, call 
DisposeControl to remove it from its window's control list and release the 
memory it occupies. To dispose of all of a given window's controls at once, use 
KillControls. 


Note: The Window Manager procedures DisposeWindow and CloseWindow 
automatically dispose of all the controls associated with the 
given window. 


When the Toolbox Event Manager function GetNextEvent reports that an update 
event has occurred for a window, the application should call DrawControls to 
redraw the window's controls as part of the process of updating the window. 


After receiving a mouse-down event from GetNextEvent, do the following: 


1. First call FindWindow to determine which part of which window the 
mouse button was pressed in. 


2. If it was in the content region of the active window, call FindControl 
for that window to find out whether it was in an active control, and 
if so, in which part of which control. 


3. Finally, take whatever action is appropriate when the user presses 
the mouse button in that part of the control, using routines such 
as TrackControl (to perform some action repeatedly for as long as 
the mouse button is down, or to allow the user to drag the control's 
indicator with the mouse), DragControl (to pull an outline of the 
control across the screen and move the control to a new location), 
and HiliteControl (to change the way the control is highlighted). 


For the standard control types, step 3 involves calling TrackControl. 
TrackControl handles the highlighting of the control and determines whether the 
mouse is still in the control when the mouse button is released. It also handles 
the dragging of the thumb in a scroll bar and, via your action procedure, the 
response to presses or clicks in the other parts of a scroll bar. When 
TrackControl returns the part code for a button, check box, or radio button, the 
application must do whatever is appropriate as a response to a click of that 
control. When TrackControl returns the part code for the thumb of a scroll bar, 
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the application must scroll to the corresponding relative position in the 
document. 


The application's exact response to mouse activity in a control that retains a 
setting will depend on the current setting of the control, which is available 
from the GetCtlValue function. For controls whose values can be set by the user, 
the SetCtlValue procedure may be called to change the control's setting and 
redraw the control accordingly. You'll call SetCtlValue, for example, when a 
check box or radio button is clicked, to change the setting and draw or clear 
the mark inside the control. 


Wherever needed in your program, you can call HideControl to make a control 
invisible or ShowControl to make it visible. Similarly, MoveControl, which 
simply changes a control's location without pulling around an outline of it, can 
be called at any time, as can SizeControl, which changes its size. For example, 
when the user changes the size of a document window that contains a scroll bar, 
you'll call HideControl to remove the old scroll bar, MoveControl and 
SizeControl to change its location and size, and ShowControl to display it as 
changed. 


Whenever necessary, you can read various attributes of a control with GetCTitle, 
GetCtlMin, GetCtlMax, GetCRefCon, or GetCtlAction; you can change them with 
SetCTitle, SetCtlMin, SetCtlMax, SetCRefCon, or SetCtlAction. 
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USING COLOR CONTROLS 


The following caveats apply to the use of color with controls: 


« Controls are drawn in the window port, which by default is an 
old-style GrafPort. This limits color matching to the eight old 
QuickDraw colors. To achieve full RGB display with controls, the 
window must be opened as a cGrafPort, using NewCWindow, GetNewCWindow, 
or any other window routine that creates a color window. 


Since there is no "InitControls" call, a default AuxCtlRec is created and 
intialized on the application heap when InitWindows is executed. When a new 
control is created with the NewControl routine, no entry is added to the 
AuxList, and the control will use the default colors. If SetCtlColor is used 
with a different color set of a control, a new AuxList will be allocated and 
added to the head of the list. The CloseControl routine disposes of the 
AuxCtlRec. 


Often a new control is created from a 'CNTL' resource, using GetNewControl. A 
new AuxRec is allocated if the resource file contains a ‘'cctb' resource type 
with the same resource ID as the 'CNTL' resource. Otherwise, the default colors 
are used. 


The Control Manager supports controls that have color tables with more than four 
elements. To create a control with more than four colors, you must create a 
custom 'CDEF' that can access a larger color table.The interpretation of the 
partIdentifiers is determined by the 'CDEF'. If your application includes a 
'CDEF' that recognizes more than four partIdentifiers, it should use 
partIdentifiers 0-3 in the same way as the standard control defprocs. An 
application with a custom 'CDEF" should use the SysEnvirons routine upon entry 
to the defproc to determine the configuration of the system. 
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CONTROL MANAGER ROUTINES 


Initialization and Allocation 


FUNCTION NewControl (theWindow: WindowPtr; boundsRect: Rect; title: Str255; 
visible: BOOLEAN; value: INTEGER; min,max: INTEGER; 
procID: INTEGER; refCon: LONGINT) : ControlHandle; 


NewControl creates a control, adds it to the beginning of theWindow's control 
list, and returns a handle to the new control. The values passed as parameters 
are stored in the corresponding fields of the control record, as described 
below. The field that determines highlighting is set to 0 (no highlighting) and 
the pointer to the default action procedure is set to NIL (none). 


Note: The control definition function may do additional initialization, 
including changing any of the fields of the control record. The only 
standard control for which additional initialization is done is the 
scroll bar; its control definition function allocates space for a 
region to hold the thumb and stores the region handle in the 
contrlData field of the control record. 


TheWindow is the window the new control will belong to. All coordinates 
pertaining to the control will be interpreted in this window's local coordinate 
system. 


BoundsRect, given in theWindow's local coordinates, is the rectangle that 
encloses the control and thus determines its size and location. Note the 
following about the enclosing rectangle for the standard controls: 


e Simple buttons are drawn to fit the rectangle exactly. (The control 
definition function calls the QuickDraw procedure FrameRoundRect.) To 
allow for the tallest characters in the system font, there should be 
at least a 20-point difference between the top and bottom coordinates 
of the rectangle. 

e For check boxes and radio buttons, there should be at least a 16-point 
difference between the top and bottom coordinates. 

« By convention, scroll bars are 16 pixels wide, so there should be a 
16-point difference between the left and right (or top and bottom) 
coordinates. (If there isn't, the scroll bar will be scaled to fit 
the rectangle.) A standard scroll bar should be at least 48 pixels 
long, to allow room for the scroll arrows and thumb. 


Title is the control's title, if any (if none, you can just pass the empty 
string as the title). Be sure the title will fit in the control's enclosing 
rectangle; if it won't it will be truncated on the right for check boxes and 
radio buttons, or centered and truncated on both ends for simple buttons. 


Note: Some non-Roman systems write text from right-to-left, in which 
case radio buttons and check boxes are drawn with their titles 
on the left of the control. They are also truncated on the left. 
See the Script Manager chapter for more information. 
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If the visible parameter is TRUE, NewControl draws the control. 


Note: It does not use the standard window updating mechanism, but 
instead draws the control immediately in the window. 


The min and max parameters define the control's range of possible settings; the 
value parameter gives the initial setting. For controls that don't retain a 
setting, such as buttons, the values you supply for these parameters will be 
stored in the control record but will never be used. So it doesn't matter what 
values you give for those controls—0 for all three parameters will do. For 
controls that just retain an on-or-off setting, such as check boxes or radio 
buttons, min should be 0 (meaning the control is off) and max should be 1 
(meaning it's on). For dials, you can specify whatever values are appropriate 
for min, max, and value. 


ProcID is the control definition ID, which leads to the control definition 
function for this type of control. (The function is read into memory if it 

isn't already in memory.) The control definition IDs for the standard control 
types are listed above under "Controls and Resources". Control definition IDs 
for custom control types are discussed later under "Defining Your Own Controls". 


RefCon is the control's reference value, set and used only by your application. 


FUNCTION GetNewControl (controlID: INTEGER; 
theWindow: WindowPtr) : ControlHandle; 


GetNewControl creates a control from a control template stored in a resource 
file, adds it to the beginning of theWindow's control list, and returns a handle 
to the new control. ControlID is the resource ID of the template. GetNewControl 
works exactly the same as NewControl (above), except that it gets the initial 
values for the new control's fields from the specified control template instead 
of accepting them as parameters. If the control template can't be read from the 
resource file, GetNewControl returns NIL. It releases the memory occupied by the 
resource before returning. 


PROCEDURE DisposeControl (theControl: ControlHandle) ; 


Assembly-language note: The macro you invoke to call DisposeControl from 
assembly Language is named DisposControl. 


DisposeControl removes theControl from the screen, deletes it from its window's 
control list, and releases the memory occupied by the control record and any 
data structures associated with the control. 


PROCEDURE KillControls (theWindow: WindowPtr); 


KillControls disposes of all controls associated with theWindow by calling 
DisposeControl (above) for each. 


Note: Remember that the Window Manager procedures CloseWindow and 
DisposeWindow automatically dispose of all controls associated 
with the given window. 


@ SpInside Macintosh * Version 1.0 * November 1989 * Apple Computer 
THE CONTROL MANAGER ¢ 24 of 45 


Control Display 


These procedures affect the appearance of a control but not its size or 
location. 


PROCEDURE SetCTitle (theControl: ControlHandle; title: Str255); 

SetCTitle sets theControl's title to the given string and redraws the control. 
PROCEDURE GetCTitle (theControl: ControlHandle; VAR title: Str255); 
GetCTitle returns theControl's title as the value of the title parameter. 
PROCEDURE HideControl (theControl: ControlHandle) ; 


HideControl makes theControl invisible. It fills the region the control occupies 
within its window with the background pattern of the window's grafPort. It also 
adds the control's enclosing rectangle to the window's update region, so that 
anything else that was previously obscured by the control will reappear on the 
screen. If the control is already invisible, HideControl has no effect. 


PROCEDURE ShowControl (theControl: ControlHandle) ; 


ShowControl makes theControl visible. The control is drawn in its window but may 
be completely or partially obscured by overlapping windows or other objects. If 
the control is already visible, ShowControl has no effect. 


PROCEDURE DrawControls (theWindow: WindowPtr); 


DrawControls draws all controls currently visible in theWindow. The controls are 
drawn in reverse order of creation; thus in case of overlap the earliest-created 
controls appear frontmost in the window. 


Note: Window Manager routines such as SelectWindow, ShowWindow, and 
BringToFront do not automatically call DrawControls to display 
the window's controls. They just add the appropriate regions to 
the window's update region, generating an update event. Your program 
should always call DrawControls explicitly upon receiving an update 
event for a window that contains controls. 


PROCEDURE DrawlControl (theControl: ControlHandle); [128K ROM] 
DrawlControl draws the specified control if it's visible within the window. 
PROCEDURE UpdtControl (theWindow: WindowPtr; updateRgn: RgnHandle); [128K ROM] 


UpdtControl is a faster version of the DrawControls procedure. Instead of 
drawing all of the controls in theWindow, UpdtControl draws only the controls 
that are in the specified update region. UpdtControl is called in response to an 
update event, and is usually bracketed by calls to the Window Manager procedures 
BeginUpdate and EndUpdate. UpdateRgn should be set to the visRgn of theWindow's 
port (for more details, see the BeginUpdate procedure in the Window Manager 
chapter). 
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Note: In general, controls are in a dialog box and are automatically 
drawn by the DrawDialog procedure. 


PROCEDURE HiliteControl (theControl: ControlHandle; hiliteState: INTEGER); 


HiliteControl changes the way theControl is highlighted. HiliteState has one of 
the following values: 


e The value 0 means no highlighting. (The control is active.) 

¢ A value between 1 and 253 is interpreted as a part code designating 
the part of the (active) control to be highlighted. 

e The value 255 means that the control is to be made inactive and 
highlighted accordingly. 


Note: The value 254 should not be used; this value is reserved for future use. 


HiliteControl calls the control definition function to redraw the control with 
its new highlighting. 


Mouse Location 


FUNCTION FindControl (thePoint: Point; theWindow: WindowPtr; VAR whichControl: 
ControlHandle) : INTEGER; 


When the Window Manager function FindWindow reports that the mouse button was 
pressed in the content region of a window, and the window contains controls, the 
application should call FindControl with theWindow equal to the window pointer 
and thePoint equal to the point where the mouse button was pressed (in the 
window's local coordinates). FindControl tells which of the window's controls, 
if any, the mouse button was pressed in: 


e If it was pressed in a visible, active control, FindControl sets the 
whichControl parameter to the control handle and returns a part code 
identifying the part of the control that it was pressed in. 

e If it was pressed in an invisible or inactive control, or not in any 
control, FindControl sets whichControl to NIL and returns 0 as its result. 


Warning: Notice that FindControl expects the mouse point in the window's 
local coordinates, whereas FindWindow expects it in global 
coordinates. Always be sure to convert the point to local 
coordinates with the QuickDraw procedure GlobalToLocal before 
calling FindControl. 


Note: FindControl also returns NIL for whichControl and 0 as its result 
if the window is invisible or doesn't contain the given point. In 
these cases, however, FindWindow wouldn't have returned this window 
in the first place, so the situation should never arise. 


FUNCTION TrackControl (theControl: ControlHandle; startPt: Point; 
actionProc: ProcPtr) : INTEGER; 


When the mouse button is pressed in a visible, active control, the application 
should call TrackControl with theControl equal to the control handle and startPt 
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equal to the point where the mouse button was pressed (in the local coordinates 
of the control's window). TrackControl follows the movements of the mouse and 
responds in whatever way is appropriate until the mouse button is released; the 
exact response depends on the type of control and the part of the control in 
which the mouse button was pressed. If highlighting is appropriate, TrackControl 
does the highlighting, and undoes it before returning. When the mouse button is 
released, TrackControl returns with the part code if the mouse is in the same 
part of the control that it was originally in, or with 0 if not 

(in which case the application should do nothing). 


If the mouse button was pressed in an indicator, TrackControl drags a dotted 
outline of it to follow the mouse. When the mouse button is released, 
TrackControl calls the control definition function to reposition the control's 
indicator. The control definition function for scroll bars responds by redrawing 
the thumb, calculating the control's current setting based on the new relative 
position of the thumb, and storing the current setting in the control record; 
for example, if the minimum and maximum settings are 0 and 10, and the thumb is 
in the middle of the scroll bar, 5 is stored as the current setting. The 
application must then scroll to the corresponding relative position in the 
document. 


TrackControl may take additional actions beyond highlighting the control or 
dragging the indicator, depending on the value passed in the actionProc 
parameter, as described below. The following tells you what to pass for the 
standard control types; for a custom control, what you pass will depend on how 
the control is defined. 


e If actionProc is NIL, TrackControl performs no additional actions. This 
is appropriate for simple buttons, check boxes, radio buttons, and the 
thumb of a scroll bar. 

e ActionProc may be a pointer to an action procedure that defines some 
action to be performed repeatedly for as long as the user holds down 
the mouse button. (See below for details.) 

¢ If actionProc is POINTER(-—1), TrackControl looks in the control record 
for a pointer to the control's default action procedure. If that field 
of the control record contains a procedure pointer, TrackControl uses 
the action procedure it points to; if the field contains POINTER (-1), 
TrackControl calls the control definition function to perform the 
necessary action. (If the field contains NIL, TrackControl does nothing. ) 


The action procedure in the control definition function is described in the 
section "Defining Your Own Controls". The following paragraphs describe only the 
action procedure whose pointer is passed in the actionProc parameter or stored 
in the control record. 


If the mouse button was pressed in an indicator, the action procedure (if any) 
should have no parameters. This procedure must allow for the fact that the mouse 
may not be inside the original control part. 


If the mouse button was pressed in a control part other than an indicator, the 
action procedure should be of the form 


PROCEDURE MyAction (theControl: ControlHandle; partCode: INTEGER); 
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In this case, TrackControl passes the control handle and the part code to the 
action procedure. (It passes 0 in the partCode parameter if the mouse has moved 
outside the original control part.) As an example of this type of action 
procedure, consider what should happen when the mouse button is pressed in a 
scroll arrow or paging region in a scroll bar. For these cases, your action 
procedure should examine the part code to determine exactly where the mouse 
button was pressed, scroll up or down a line or page as appropriate, and call 
SetCtlValue to change the control's setting and redraw the thumb. 


Warning: Since it has a different number of parameters depending on whether 
the mouse button was pressed in an indicator or elsewhere, the 
action procedure you pass to TrackControl (or whose pointer you 
store in the control record) can be set up for only one case or 
the other. If you store a pointer to a default action procedure 
in a control record, be sure it will be used only when appropriate 
for that type of action procedure. The only way to specify actions 
in response to all mouse-down events in a control, regardless of 
whether they're in an indicator, is via the control definition 
function. 


Assembly-language note: If you store a pointer to a procedure in the global 
variable DragHook, that procedure will be called 
repeatedly (with no parameters) for as long as the 
user holds down the mouse button. TrackControl 
invokes the Window Manager macro DragTheRgn, 
which calls the DragHook procedure. DragTheRgn 
uses the pattern stored in the global variable 
DragPattern for the dragged outline of the indicator. 


FUNCTION TestControl (theControl: ControlHandle; thePoint: Point) : INTEGER; 


If theControl is visible and active, TestControl tests which part of the control 
contains thePoint (in the local coordinates of the control's window); it returns 
the corresponding part code, or 0 if the point is outside the control. If the 
control is invisible or inactive, TestControl returns 0. TestControl is called 
by FindControl and TrackControl; normally you won't need to call it yourself. 


Control Movement and Sizing 
PROCEDURE MoveControl (theControl: ControlHandle; h,v: INTEGER); 


MoveControl moves theControl to a new location within its window. The top left 
corner of the control's enclosing rectangle is moved to the horizontal and 
vertical coordinates h and v (given in the local coordinates of the control's 
window); the bottom right corner is adjusted accordingly, to keep the size of 
the rectangle the same as before. If the control is currently visible, it's 
hidden and then redrawn at its new location. 


PROCEDURE DragControl (theControl: ControlHandle; startPt: Point; 
LimitRect,slopRect: Rect; axis: INTEGER); 


Called with the mouse button down inside theControl, DragControl pulls a dotted 
outline of the control around the screen, following the movements of the mouse 
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until the button is released. When the mouse button is released, DragControl 
calls MoveControl to move the control to the location to which it was dragged. 


Note: Before beginning to follow the mouse, DragControl calls the control 
definition function to allow it to do its own "custom dragging" if 
it chooses. If the definition function doesn't choose to do any 
custom dragging, DragControl uses the default method of dragging 
described here. 


The startPt, limitRect, slopRect, and axis parameters have the same meaning as 
for the Window Manager function DragGrayRgn. These parameters are reviewed 
briefly below; see the description of DragGrayRgn in the Window Manager chapter 
for more details. 


e StartPt is assumed to be the point where the mouse button was originally 
pressed, in the local coordinates of the control's window. 

e LimitRect limits the travel of the control's outline, and should normally 
coincide with or be contained within the window's content region. 

¢ SlopRect allows the user some "slop" in moving the mouse; it should 
completely enclose limitRect. 

¢ The axis parameter allows you to constrain the control's motion to 
only one axis. It has one of the following values: 


CONST noConstraint = 0; {no constraint} 
hAxisOnly = 1; {horizontal axis only} 
vAxisOnly = 2; {vertical axis only} 


Assembly-language note: Like TrackControl, DragControl invokes the 
macro DragTheRgn, so you can use the global 
variables DragHook and DragPattern. 


PROCEDURE SizeControl (theControl: ControlHandle; w,h: INTEGER); 


SizeControl changes the size of theControl's enclosing rectangle. The bottom 
right corner of the rectangle is adjusted to set the rectangle's width and 
height to the number of pixels specified by w and h; the position of the top 
left corner is not changed. If the control is currently visible, it's hidden and 
then redrawn in its new size. 


Control Setting and Range 
PROCEDURE SetCtlValue (theControl: ControlHandle; theValue: INTEGER); 


SetCtlValue sets theControl's current setting to theValue and redraws the 
control to reflect the new setting. For check boxes and radio buttons, the value 
1 fills the control with the appropriate mark, and © clears it. For scroll bars, 
SetCtlValue redraws the thumb where appropriate. 


If the specified value is out of range, it's forced to the nearest endpoint of 
the current range (that is, if theValue is less than the minimum setting, 
SetCtlValue sets the current setting to the minimum; if theValue is greater than 
the maximum setting, it sets the current setting to the maximum). 
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FUNCTION GetCtlValue (theControl: ControlHandle) : INTEGER; 
GetCtlValue returns theControl's current setting. 
PROCEDURE SetCtlMin (theControl: ControlHandle; minValue: INTEGER); 


Assembly-language note: The macro you invoke to call SetCtlMin from 
assembly Language is named SetMinCtl. 


SetCtlMin sets theControl's minimum setting to minValue and redraws the control 
to reflect the new range. If the control's current setting is less than 
minValue, the setting is changed to the new minimum. 

FUNCTION GetCtlMin (theControl: ControlHandle) : INTEGER; 


Assembly-language note: The macro you invoke to call GetCtlMin from 
assembly Language is named GetMinCtl. 


GetCtlMin returns theControl's minimum setting. 
PROCEDURE SetCtlMax (theControl: ControlHandle; maxValue: INTEGER); 


Assembly-language note: The macro you invoke to call SetCtlMax from 
assembly Language is named SetMaxCtl. 


SetCtlMax sets theControl's maximum setting to maxValue and redraws the control 
to reflect the new range. If the control's current setting is greater than 
maxValue, the setting is changed to the new maximum. 

Note: If you set the maximum setting of a scroll bar equal to its minimum 
setting, the control definition function will make the scroll bar 
inactive. 

FUNCTION GetCtlMax (theControl: ControlHandle) : INTEGER; 


Assembly-language note: The macro you invoke to call GetCtlMax from 
assembly Language is named GetMaxCtl. 


GetCtlMax returns theControl's maximum setting. 


Miscellaneous Routines 

PROCEDURE SetCRefCon (theControl: ControlHandle; data: LONGINT); 
SetCRefCon sets theControl's reference value to the given data. 

FUNCTION GetCRefCon (theControl: ControlHandle) : LONGINT; 

GetCRefCon returns theControl's current reference value. 

PROCEDURE SetCtlAction (theControl: ControlHandle; actionProc: ProcPtr); 


SetCtlAction sets theControl's default action procedure to actionProc. 
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FUNCTION GetCtlAction (theControl: ControlHandle) : ProcPtr; 


GetCtlAction returns a pointer to theControl's default action procedure, if any. 
(It returns whatever is in that field of the control record.) 


The following new Control Manager routines can be used as noted below for the 
Macintosh Plus, the Macintosh SE, and the Macintosh II. 


FUNCTION GetCVariant (theControl: ControlHandle) : INTEGER; 
[Macintosh Plus, Macintosh SE, and Macintosh ITI] 


The GetVariant function returns the variant control value for the control 
described by theControl. This value was formerly stored in the high four bits of 
the control defproc handle; for future compatibility, use the GetCVariant 
routine to access this value. 


PROCEDURE SetCtlColor (theControl: ControlHandle; newColorTable: CCTabHandle) ; 
[Macintosh IT] 


The SetCtlColor procedure sets or modifies a control's color table. If the 
control currently has no auxiliary control record, a new one is created with the 
given color table and added to the head of the auxiliary control list. If there 
is already an auxiliary record for the control, its color table is replaced by 
the contents of newColorTable. 


If newColorTable has the same contents as the default color table, the 
control's existing auxiliary record and color table are removed from the 
auxiliary control list and deallocated. If theControl = NIL, the operation 
modifies the default color table itself. If the control is visible, it will be 
redrawn by SetCtlColor using the new color table. 


FUNCTION GetAuxCtl (theControl: ControlHandle; 
VAR acHndl: AuxCtlHandle) : BOOLEAN; [Macintosh ITI] 


The GetAuxCtl function returns a handle to a control's AuxCtlRec: 


e If the given control has its own color table, the function returns TRUE. 

¢ If the control used the default color set, the function returns FALSE. 

¢ If the control asked to receive the default color set (theControl = NIL), 
then the function returns TRUE. 
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DEFINING YOUR OWN CONTROLS 


In addition to the standard, built-in control types (buttons, check boxes, radio 
buttons, and scroll bars), the Control Manager allows you to define 

"custom" control types of your own. Maybe you need a three-way selector switch, 
a memory-space indicator that looks like a thermometer, or a thruster control 
for a spacecraft simulator—whatever your application calls for. Controls and 
their indicators may occupy regions of any shape, in the full generality 
permitted by QuickDraw. 


To define your own type of control, you write a control definition function and 
store it in a resource file. When you create a control, you provide a control 
definition ID, which leads to the control definition function. The control 
definition ID is an integer that contains the resource ID of the control 
definition function in its upper 12 bits and a variation code in its lower four 
bits. Thus, for a given resource ID and variation code, the control definition 
ID is 


16 * resource ID + variation code 


For example, buttons, check boxes, and radio buttons all use the standard 
definition function whose resource ID is 0, but they have variation codes of 0, 
1, and 2, respectively. 


The Control Manager calls the Resource Manager to access the control definition 
function with the given resource ID. The Resource Manager reads the control 
definition function into memory and returns a handle to it. The Control Manager 
stores this handle in the contrlDefProc field of the control record. In 24-bit 
addressing mode, the variation code is placed in the high-order byte of this 
field; in 32-bit mode, the variation code is placed in the most significant byte 
of the acReserved field in the control's AuxCtlRec. Later, when it needs to 
perform a type-dependent action on the control, it calls the control definition 
function and passes it the variation code as a parameter. Figure 7 illustrates 
this process. 


Keep in mind that the calls your application makes to use a control depend 
heavily on the control definition function. What you pass to the TrackControl 
function, for example, depends on whether the definition function contains an 
action procedure for the control. Just as you need to know how to call 
TrackControl for the standard controls, each custom control type will have a 
particular calling protocol that must be followed for the control to work 
properly. 


The Control Definition Function 


The control definition function is usually written in assembly language, but may 
be written in Pascal. 
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You supply the control definition ID: 
15 4 3 O 


ID [resource ID of contro] definition 
pee 1B eeeleenes) 
The Control Manager call: the Resource Manager with 

defHandle := GetResource ("CDEF'), resource] 


and stores into the contrhlDefProc field of the control record: 


a a 


The variation code is passed to the control definition Function. 


Figure 7-Control Definition Passing 
Figure 7—Control Definition Handling 
Assembly-language note: The function's entry point must be at the beginning. 


You can give your control definition function any name you like. Here's how you 
would declare one named MyControlL: 


FUNCTION MyControl (varCode: INTEGER; theControl: ControlHandle; 
message: INTEGER; param: LONGINT) : LONGINT; 


VarCode is the variation code, as described above. 
TheControl is a handle to the control that the operation will affect. 


The message parameter identifies the desired operation. It has one of the 
following values: 


CONST drawCntl = 0; {draw the control (or control part)} 
testCntl =15; {test where mouse button was pressed} 
calcCRgns = 2; {calculate control's region (or indicator's)} 
initCntl = 3; {do any additional control initialization} 
dispCntl = 4; {take any additional disposal actions} 
posCntl = 5; {reposition control's indicator and update it} 
thumbCntl = 6; {calculate parameters for dragging indicator} 
dragCntl = 7; {drag control (or its indicator) } 
autoTrack = 8; {execute control's action procedure} 


As described below in the discussions of the routines that perform these 
operations, the value passed for param, the last parameter of the control 
definition function, depends on the operation. Where it's not mentioned below, 
this parameter is ignored. Similarly, the control definition function is 
expected to return a function result only where indicated; in other cases, the 
function should return 0. 


In some cases, the value of param or the function result is a part code. The 
part code 128 is reserved for future use and shouldn't be used for parts of your 
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controls. Part codes greater than 128 should be used for indicators; however, 
129 has special meaning to the control definition function, as described below. 


Note: "Routine" here doesn't necessarily mean a procedure or function. 
While it's a good idea to set these up as subprograms inside the 
control definition function, you're not required to do so. 


A new version of the control definition function (version 4 or greater) in the 
128K ROM allows buttons, check boxes, and radio buttons to have multiple lines 
of text in their titles. When specifying the title with either NewControl or 
SetCTitle, simply separate the lines with the ASCII character code $0D 
(carriage return). You can also use a version of the Resource Editor that 
supports the 128K ROM to specify multiline titles. 


Note: This feature will work with the 64K ROM if the new version of 
the control definition function is in the system resource file. 


If the control is a button, each line is horizontally centered and separated 
from the neighboring lines by the font's leading. (Since the height of each line 
is equal to the ascent plus descent plus leading of the font used, be sure to 
make the total height of the enclosing rectangle greater than the number of 
lines times this height. ) 


If the control is a check box or a radio button, the text is left-justified and 
the check box or button is vertically centered within the enclosing rectangle, 
cntrlRect. 


Note: The text is right-justified on check boxes and radio buttons if 
running under a non-Roman system that draws text from right-to-left. 
See the Script Manager chapter for more information. 


The Draw Routine 


The message drawCntl asks the control definition function to draw all or part of 
the control within its enclosing rectangle. The value of param is a part code 
specifying which part of the control to draw, or 0 for the entire control. If 
the control is invisible (that is, if its contrlVis field is 0), there's nothing 
to do; if it's visible, the definition function should draw it (or the requested 
part), taking into account the current values of its contrlHilite and 
contrlValue fields. The control may be either scaled or clipped to the enclosing 
rectangle. 


If param is the part code of the control's indicator, the draw routine can 
assume that the indicator hasn't moved; it might be called, for example, to 
highlight the indicator. There's a special case, though, in which the draw 
routine has to allow for the fact that the indicator may have moved: This 
happens when the Control Manager procedures SetCtlValue, SetCtlMin, and 
SetCtlMax call the control definition function to redraw the indicator after 
changing the control setting. Since they have no way of knowing what part code 
you chose for your indicator, they all pass 129 to mean the indicator. The draw 
routine must detect this part code as a special case, and remove the indicator 
from its former location before drawing it. 


Note: If your control has more than one indicator, 129 should be 
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interpreted to mean all indicators. 


The Test Routine 


The Control Manager function FindControl sends the message testCntl to the 
control definition function when the mouse button is pressed in a visible 
control. This message asks in which part of the control, if any, a given point 
lies. The point is passed as the value of param, in the local coordinates of the 
control's window; the vertical coordinate is in the high-order word of the long 
integer and the horizontal coordinate is in the low-order word. The control 
definition function should return the part code for the part of the control that 
contains the point; it should return 0 if the point is outside the control or if 
the control is inactive. 


The Routine to Calculate Regions 


The control definition function should respond to the message calcCRgns by 
calculating the region the control occupies within its window. Param is a 
QuickDraw region handle; the definition function should update this region to 
the region occupied by the control, expressed in the local coordinate system of 
its window. 


If the high-order bit of param is set, the region requested is that of the 
control's indicator rather than the control as a whole. The definition function 
should clear the high bit of the region handle before attempting to update the 
region. 


The Initialize Routine 


After initializing fields as appropriate when creating a new control, the 
Control Manager sends the message initCntl to the control definition function. 
This gives the definition function a chance to perform any type-specific 
initialization it may require. For example, if you implement the control's 
action procedure in its control definition function, you'll set up the 
initialize routine to store POINTER(-—1) in the contrlAction field; TrackControl 
calls for this control would pass POINTER(—1) in the actionProc parameter. 


The control definition function for scroll bars allocates space for a region to 
hold the scroll bar's thumb and stores the region handle in the contrlData field 
of the new control record. The initialize routine for standard buttons, check 
boxes, and radio buttons does nothing. 


The Dispose Routine 


The Control Manager's DisposeControl procedure sends the message dispCntl to the 
control definition function, telling it to carry out any additional actions 
required when disposing of the control. For example, the standard definition 
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function for scroll bars releases the space occupied by the thumb region, whose 
handle is kept in the control's contrlData field. The dispose routine for 
standard buttons, check boxes, and radio buttons does nothing. 


The Drag Routine 


The message dragCntl asks the control definition function to drag the control or 
its indicator around on the screen to follow the mouse until the user releases 
the mouse button. Param specifies whether to drag the indicator or the whole 
control: @ means drag the whole control, while a nonzero value means drag only 
the indicator. 


The control definition function need not implement any form of "custom 
dragging"; if it returns a result of 0, the Control Manager will use its own 
default method of dragging (calling DragControl to drag the control or the 
Window Manager function DragGrayRgn to drag its indicator). Conversely, if the 
control definition function chooses to do its own custom dragging, it should 
signal the Control Manager not to use the default method by returning a nonzero 
result. 


If the whole control is being dragged, the definition function should call 
MoveControl to reposition the control to its new location after the user 
releases the mouse button. If just the indicator is being dragged, the 
definition function should execute its own position routine (see below) to 
update the control's setting and redraw it in its window. 


The Position Routine 


For controls that don't use the Control Manager's default method of dragging the 
control's indicator (as performed by DragGrayRgn), the control definition 
function must include a position routine. When the mouse button is released 
inside the indicator of such a control, TrackControl calls the control 
definition function with the message posCntl to reposition the indicator and 
update the control's setting accordingly. The value of param is a point giving 
the vertical and horizontal offset, in pixels, by which the indicator is to be 
moved relative to its current position. (Typically, this is the offset between 
the points where the user pressed and released the mouse button while dragging 
the indicator.) The vertical offset is given in the high-order word of the long 
integer and the horizontal offset in the low-order word. The definition function 
should calculate the control's new setting based on the given offset, update the 
contrlValue field, and redraw the control within its window to reflect the new 
setting. 


Note: The Control Manager procedures SetCtlValue, SetCtlMin, and SetCtlMax 
do not call the control definition function with this message; instead, 
they pass the drawCntl message to execute the draw routine (see above). 


The Thumb Routine 
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Like the position routine, the thumb routine is required only for controls that 
don't use the Control Manager's default method of dragging the control's 
indicator. The control definition function for such a control should respond to 
the message thumbCntl by calculating the limiting rectangle, slop rectangle, and 
axis constraint for dragging the control's indicator. Param is a pointer to the 
following data structure: 


RECORD 
LlimitRect,slopRect: Rect; 
axis: INTEGER 

END; 


On entry, param®.limitRect.topLeft contains the point where the mouse button was 
first pressed. The definition function should store the appropriate values into 

the fields of the record pointed to by param; they're analogous to the similarly 
named parameters to DragGrayRgn. 


The Track Routine 


You can design a control to have its action procedure in the control definition 
function. To do this, set up the control's initialize routine to store 
POINTER(—1) in the contrlAction field of the control record, and pass 
POINTER(—1) in the actionProc parameter to TrackControl. TrackControl will 
respond by calling the control definition function with the message autoTrack. 
The definition function should respond like an action procedure, as discussed in 
detail in the description of TrackControl. It can tell which part of the control 
the mouse button was pressed in from param, which contains the part code. The 
track routine for each of the standard control types does nothing. 
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FORMATS OF RESOURCES FOR CONTROLS 


The GetNewControl function takes the resource ID of a control template as a 
parameter, and gets from that template the same information that the NewControl 
function gets from eight of its parameters. The resource type for a control 
template is 'CNTL', and the resource data has the following format: 


Number of bytes Contents 

8 bytes Same as boundsRect parameter to NewControl 
2 bytes Same as value parameter to NewControl 

2 bytes Same as visible parameter to NewControl 

2 bytes Same aS max parameter to NewControl 

2 bytes Same as min parameter to NewControl 

2 bytes Same as procID parameter to NewControl 

4 bytes Same as refCon parameter to NewControl 

n bytes Same as title parameter to NewControl 


(1-byte length in bytes, followed by the 
characters of the title) 


The resource type for a control definition function is 'CDEF'. The resource data 
is simply the compiled or assembled code of the function. 
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SUMMARY OF THE CONTROL MANAGER 


Constants 
CONST 


{ Control definition IDs } 


pushButProc = 0; {simple button} 

checkBoxProc = 1; {check box} 

radioButProc = 2; {radio button} 

useWFont = 8; {add to above to use window's font} 
scrollBarProc = 16; {scroll bar} 

{ Part codes } 

inButton = 10; {simple button} 

inCheckBox = 11; {check box or radio button} 
inUpButton = 20; {up arrow of a scroll bar} 
inDownButton = 21; {down arrow of a scroll bar} 
inPageUp = 22; {"page up" region of a scroll bar} 
inPageDown = 23; {"page down" region of a scroll bar} 
inThumb = 129; {thumb of a scroll bar} 


{ Axis constraints for DragControl } 


noConstraint = 0; {no constraint} 
hAxisOnly = 1; {horizontal axis only} 
vAxisOnly = 2; {vertical axis only} 


{ Messages to control definition function } 


drawCntl = 0; {draw the control (or control part)} 

testCntl =15; {test where mouse button was pressed} 
calcCRgns = 2; {calculate control's region (or indicator's)} 
initCntl = 3; {do any additional control initialization} 
dispCntl = 4; {take any additional disposal actions} 

posCntl = 5; {reposition control's indicator and update it} 
thumbCntl = 6; {calculate parameters for dragging indicator} 
dragCntl = 7; {drag control (or its indicator) } 

autoTrack = 8; {execute control's action procedure} 


{ Control part colors } 


cFrameColor 
cBodyColor 
cTextColor 
cThumbColor 


WNr® 
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Data Types 


TYPE 
ControlPtr = “ControlRecord; 
ControlHandle = “*ControlPtr; 
ControlRecord = 
PACKED RECORD 
nextControl: ControlHandle; {next control} 
contrlOwner: WindowPtr; {control's window} 
contrlRect: Rect; {enclosing rectangle} 
contrlVis: Byte; {255 if visible} 
contrlHilite: Byte; {highlight state} 
contrlValue: INTEGER; {control's current setting} 
contrlMin: INTEGER; {control's minimum setting} 
contrlMax: INTEGER; {control's maximum setting} 
contrlDefProc: Handle; {control definition function} 
contrlData: Handle; {data used by contrlDefProc} 
contrlAction: ProcPtr; {default action procedure} 
contrlRfCon: LONGINT; {control's reference value} 
contrlTitle: Str255 {control's title} 
END; 
AuxCtlHandle = *AuxCtlPtr; 
AuxCtlPtr = “AuxCtlRec; 
AuxCtlRec = RECORD 
acNext: AuxCtlHandle; {handle to next record in list} 
acOwner: ControlHandle; {handle to owning control} 
acCTable: CCTabHandle; {handle to control's color } 
{ table} 
acFlags: INTEGER; {miscellaneous flags; reserved} 
acReserved: LONGINT; {reserved for future expansion} 
acRefCon: LONGINT {reserved for application use} 
END; 
CCTabHandle = *CCTabPtr; 
CCTabPtr = “CtlCTab; 
CtlCTab = RECORD 
ccSeed: LONGINT; {not used for controls} 
ccRider: INTEGER; {not used for controls} 
ctSize: INTEGER; {number of entries in table —1} 
ctTable: cSpecArray {array of ColorSpec records} 
END; 
Routines 


Initialization and Allocation 


FUNCTION NewControl (theWindow: WindowPtr; boundsRect: Rect; 
title: Str255; visible: BOOLEAN; value: INTEGER; 
min,max: INTEGER; procID: INTEGER; 
refCon: LONGINT) ControlHandle; 
FUNCTION GetNewControl (controlID: INTEGER; 
theWindow: WindowPtr) ControlHandle; 
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PROCEDURE DisposeControl (theControl: 


PROCEDURE KillControls (theWindow: 


Control Display 


ControlHandle) ; 
WindowPtr) ; 


PROCEDURE SetCTitle (theControl: ControlHandle; title: Str255); 
PROCEDURE GetCTitle (theControl: ControlHandle; VAR title: Str255); 
PROCEDURE HideControl (theControl: ControlHandle) ; 
PROCEDURE ShowControl (theControl: ControlHandle) ; 
PROCEDURE DrawControls (theWindow: WindowPtr); 
PROCEDURE DrawlControl (theControl: ControlHandle); [128K ROM] 
PROCEDURE UpdtControl (theWindow: WindowPtr; 
updateRgn: RgnHandle); [128K ROM] 

PROCEDURE HiliteControl (theControl: ControlHandle; hiliteState: INTEGER); 
Mouse Location 
FUNCTION FindControl (thePoint: Point; theWindow: WindowPtr; 

VAR whichControl: ControlHandle) INTEGER; 
FUNCTION TrackControl (theControl: ControlHandle; startPt: Point; 

actionProc: ProcPtr) INTEGER; 
FUNCTION TestControl (theControl: ControlHandle; 

thePoint: Point) INTEGER; 
Control Movement and Sizing 
PROCEDURE MoveControl (theControl: ControlHandle; h,v: INTEGER); 
PROCEDURE DragControl (theControl: ControlHandle; startPt: Point; 

LimitRect,slopRect: Rect; axis: INTEGER); 
PROCEDURE SizeControl (theControl: ControlHandle; w,h: INTEGER); 
Control Setting and Range 
PROCEDURE SetCtlValue (theControl: ControlHandle; theValue: INTEGER); 
FUNCTION GetCtlValue (theControl: ControlHandle) INTEGER; 
PROCEDURE SetCtlMin (theControl: ControlHandle; minValue: INTEGER); 
FUNCTION GetCtlMin (theControl: ControlHandle) INTEGER; 
PROCEDURE SetCtlMax (theControl: ControlHandle; maxValue INTEGER) ; 
FUNCTION GetCtlMax (theControl: ControlHandle) INTEGER; 
Miscellaneous Routines 
PROCEDURE SetCRefCon (theControl: ControlHandle; data: LONGINT); 
FUNCTION GetCRefCon (theControl: ControlHandle) LONGINT; 
PROCEDURE SetCtlAction (theControl: ControlHandle; actionProc ProcPtr); 
FUNCTION GetCtlAction (theControl: ControlHandle) ProcPtr; 
PROCEDURE SetCtlColor (theControl: ControlHandle; 

newColorTable: CCTabHandle) ; 

FUNCTION GetAuxCtl (theControl: ControlHandle; 

VAR acHndl: AuxWinHandle): BOOLEAN; 
FUNCTION GetCVariant (theControl: ControlHandle) : INTEGER; 


Action Procedure for TrackControl 
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If an indicator: PROCEDURE MyAction; 
If not an indicator: PROCEDURE MyAction (theControl: ControlHandle; 


partCode: INTEGER); 


Control Definition Function 


FUNCTION MyControl (varCode: INTEGER; theControl: ControlHandle; 


message: INTEGER; param: LONGINT) : LONGINT; 


Global Variables 


AuxWinHead 


Contains a pointer to the linked list of auxiliary 
control records. 


Assembly-Language Information 


Constants 


» Control definition IDs 


pushButProc 
checkBoxProc 
radioButProc 
useWFont 


scrollBarProc .EQU 


» Part codes 


inButton 
inCheckBox 
inUpButton 
inDownButton 
inPageUp 
inPageDown 
inThumb 


-EQU 0 ;simple button 

.EQU 1 scheck box 

.EQU 2 sradio button 

.EQU 8 sadd to above to use window's font 
16 ;scroll bar 


-EQU 10 ;simple button 

.-EQU 11 = ;check box or radio button 

.-EQU 20 ;up arrow of a scroll bar 

.-EQU 21 ;down arrow of a scroll bar 

.-EQU 22 ;"page up" region of a scroll bar 
.EQU 23 ;"page down" region of a scroll bar 
-EQU 129 ;thumb of a scroll bar 


; Axis constraints for DragControl 


noConstraint 
hAxisOnly 
vAxisOnly 


.EQU 0 sno constraint 
.EQU 1 ;horizontal axis only 
.EQU 2 ;vertical axis only 


; Messages to control definition function 


drawCtlMsg 
hitCtlMsg 
calcCtlMsg 
newCtlMsg 


.EQU 0 ;draw the control (or control part) 


.EQU 1 ;test where mouse button was pressed 
.EQU 2 ;calculate control's region (or indicator's) 
.EQU 3 ;do any additional control initialization 
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dispCtlMsg .EQU 4 ;take any additional disposal actions 
posCtlMsg .EQU 5 ;reposition control's indicator and update it 
thumbCtlMsg .EQU 6 ;calculate parameters for dragging indicator 
dragCtlMsg .EQU 7 ;drag control (or its indicator) 

trackCtlMsg -EQU 8 ;execute control's action procedure 


sauxCtlRec structure 


acnext EQU $0 ;[handle] next in chain 
acOwner EQU $4 ;[ControlHandle] owner ID 
acCTable EQU $8 ;[CTabHandle] color table 
acFlags EQU $C ;[word] miscellaneous flags 
acReserved EQU  $E ;[LONGINT] for expansion 
acRefCon EQU $18 ;[LONGINT] user constant 
auxWinSize EQU $1C ;s1ize of record 


; Equates for the colors of control parts 


cFrameColor EQU 0 

cBodyColor EQU 1 

cTextColor EQU 2 

cThumbColor EQU 3 

; Global variable 

AuxCtlHead EQU $0CD4 ‘Control Aux List head 


Control Record Data Structure 


nextControl Handle to next control in control list 

contrlOwner Pointer to this control's window 

contrlRect Control's enclosing rectangle (8 bytes) 

contrlVis 255 if control is visible (byte) 

contrlHilite Highlight state (byte) 

contrlValue Control's current setting (word) 

contrlMin Control's minimum setting (word) 

contrlMax Control's maximum setting (word) 

contrlDefHandle Handle to control definition function 

contrlData Data used by control definition function (long) 
contrlAction Address of default action procedure 

contrlRfCon Control's reference value (long) 

contrlTitle Handle to control's title (preceded by length byte) 
contrlSize Size in bytes of control record except contrlTitle field 


Special Macro Names 


Pascal name Macro name 
DisposeControl _DisposControl 
GetCtlMax _GetMaxCtl 
GetCtlMin _GetMinCtl 
SetCtlMax _SetMaxCtl 
SetCtlMin _SetMinCtl 
Variables 
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DragHook Address of procedure to execute during TrackControl 
and DragControl 
DragPattern Pattern of dragged region's outline (8 bytes) 
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Further Reference: 


Resource Manager 

QuickDraw 

Toolbox Event Manager 

Window Manager 

Script Manager 

Technical Note #196, 'CDEF' Parameters and Bugs 
Technical Note #212, The Joy Of Being 32-Bit Clean 


END OF DOCUMENT 
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